<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<!-- /*
 * NAME
 *      $RCSfile: Contents.html,v $
 * DESCRIPTION
 *      [given below]
 * DELTA
 *      $Revision: 1.23 $
 *      $Author: birgita $
 * CREATED
 *      $Date: 2009/03/18 12:15:41 $
 * COPYRIGHT
 *      Westhawk Ltd
 * TO DO
 *
 */ -->
<title>
Usage of Westhawk's SNMP stack
</title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
<link href="css/general.css" rel="stylesheet" type="text/css"/>
<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
</script>
<script type="text/javascript">
  _uacct = "UA-771690-2";
  urchinTracker();
</script>
</head>

<body>
<h1><a name="top">Usage of Westhawk's SNMP stack</a></h1>

<h1><a name="introduction">Introduction</a></h1>
<p>
This document describes the delivery of this stack and how the stack 
can be used for SNMPv1, SNMPv2c and SNMPv3. 
The stack supports traps, authentication and privacy. 
As authentication protocols the stack offers MD5 and SHA1. 
</p>
<p>
This document does not explain SNMP (Simple Network Management Protocol) 
itself. The reader is assumed to have basic knowledge of the protocol. 
If you want to learn more, see the <a href="#reading">Reading</a>
section.
</p>
<p>
The target applications are <em>small</em> applets, for that reason the
stack has remained tiny. We wanted something lighter that we could just
pop in a (browser) frame and leave there all day. It has no MIB
(Management Information Base)
browsing capabilities, you have to know the OID (Object Identifier) of what you want to
monitor. There are <em>many</em> other packages that do MIB browsing and
general network management.
</p>

<p>
The Westhawk Java SNMP stack comes with generated (javadoc)
<a href="./api/index.html" target="outside">documentation</a> and a
<a href="faq.html" target="outside">faq</a>. 
Check that documentation for the description of all
methods that are not mentioned in this document or for the description
of the method parameters.
</p>

<h1><a name="delivery">The delivery</a></h1>
<p>
The file <code>snmp&lt;version&gt;.zip</code> contains the SNMP stack. 
The file <code>stubBrowser&lt;version&gt;.zip</code> contains the Stub Browser
application.
Both distributions can be downloaded from the 
<a href="http://snmp.westhawk.co.uk/index.html" target="outside">
Westhawk's SNMP</a> page. 
</p>

<p>
You best unpack both deliveries in the same directory. 
They are released separately because of their
different <a href="#copyright">licence</a>, but come from the same
development source tree.
</p>


<h3 class="q"><a name="snmpzip">the contents of the snmp&lt;version&gt;.zip file</a></h3>

<dl>
<dt>build.xml</dt>
<dd>The main Ant build.xml file.</dd>

<dt>example.xml</dt>
<dd>Contains the Ant target to build and run the examples.</dd>

<dt>oracle.xml</dt>
<dd>Contains the Ant targets to build, load and run the nothread examples.</dd>


<dt>doc/</dt>
<dd>The directory with the
<a href="index.html" target="outside">documentation</a>
(including the 
<a href="./api/index.html" target="outside">javadoc</a> files).</dd>

<dt>lib/</dt>
<dd>The directory containing the jar files;
  <dl>
  <dt>- tablelayout.jar</dt>
  <dd>The jar file with the Table Layout Manager classes. This jar file is
  needed to run some of the examples. It can also be downloaded from
  our <a href="http://www.westhawk.co.uk/resources/tank.html"
  target="outside">Think Tank</a>
  page as a zip file. Unzip the <code>tablelayout.jar</code> file into
  </dd>

  <dt>- snmp&lt;version&gt;.jar</dt>
  <dd>The jar file with the core of the SNMP stack classes. It contains the 
  precompiled <code>uk.westhawk.snmp.X</code> packages. 
  This jar file does <em>not</em> contain any examples or beans.</dd>
  </dl>
</dd>

<dt>src/</dt>
<dd>The source of the SNMP stack;
    <dl>
    <dt>- uk/co/westhawk/examplev1/</dt>
    <dd>The directory with the source of 
    <a href="#example">examples</a> how to use the stack for SNMPv1. </dd>

    <dt>- uk/co/westhawk/examplev2c/</dt>
    <dd>The directory with the source of 
    <a href="#example">examples</a> how to use the stack for SNMPv2c. </dd>

    <dt>- uk/co/westhawk/examplev3/</dt>
    <dd>The directory with the source of 
    <a href="#example">examples</a> how to use the stack for SNMPv3. </dd>

    <dt>- uk/co/westhawk/nothread/</dt>
    <dd>The directory with the source of 
    <a href="../src/uk/co/westhawk/nothread/notes.html">example</a>
    how to use the stack in environments where thread creation is unwanted, 
    e.g. database JVMs such as the Oracle &trade; JVM. </dd>

    <dt>- uk/co/westhawk/snmp/beans/</dt>
    <dd>The directory with the source of the different 
    <a href="#beans">beans</a> 
    that come with the stack. </dd>

    <dt>- uk/co/westhawk/snmp/pdu/</dt>
    <dd>The directory with the source of the different 
    <a href="#pdus">PDUs</a> 
    (among other things the 
    <a href="#blocking_calls">BlockPdu</a>) that come with the stack. </dd>

    <dt>- uk/co/westhawk/snmp/stack/</dt>
    <dd>The directory with the source of the <a href="#context">context</a> 
    and ASN functionality of the stack.</dd>
    </dl>
</dd>

</dl>


<h3 class="q"><a name="stubzip">the contents of the stubBrowser&lt;version&gt;.zip file</a></h3>

<dl>
<dt>build.xml</dt>
<dd>The main Ant build.xml file. This is the same file as in the
snmp&lt;version&gt;.zip file</dd>

<dt>stub.xml</dt>
<dd>Contains the Ant targets to build and run the Stub Browser.</dd>

<dt>lib/stubBrowser&lt;version&gt;.jar</dt>
<dd>The jar file with the Stub Browser classes. It contains the 
precompiled <code>uk.westhawk.stub</code> package. 
</dd>

<dt>src/uk/co/westhawk/stub/</dt>
<dd>The directory with the source of the
<a href="#runStubBrowser">Stub Browser</a>. 
</dd>

</dl>

<h1><a name="building">Building the stack</a></h1>
<p>
You need to have Ant installed before you can build (or run) anything.
</p>
<h3 class="q"><a name="snmpjar">snmp.jar</a></h3>
<p>
To build the snmp&lt;version&gt;.jar file, type on the command line:
</p>
<pre>
% ant 
</pre>
<p>
This will compile and jar snmp&lt;version&gt;.jar and
snmpOracle&lt;version&gt;.jar in the <code>lib/</code> directory.
If you set <code>mibble.dir</code> property (see next section) it will
also build the stubBrowser&lt;version&gt;.jar file.
This target will not compile any of the examples (see 
<a href="#run">Running the applications</a>).
</p>

<h3 class="q"><a name="stubjar">stubBrowser.jar</a></h3>
<p>
Before building the stubBrowser&lt;version&gt;.jar file, you need to
download 
<a href="http://www.mibble.org" target="outside">Mibble</a> (v2.5 or later)
and set the ant <code>mibble.dir</code> property accordingly in
the <code>build.xml</code> or <code>build.properties</code> file.
</p>
<p>
Type on the command line:
</p>
<pre>
% ant buildStubBrowser
</pre>
<p>
This will compile and jar stubBrowser&lt;version&gt;.jar in the
<code>lib/</code> directory.
</p>


<h1><a name="context">The context</a></h1>
<p>
Every PDU that is created needs a context. The same context can be used for
a number of PDUs. 
</p>

<h3 class="q"><a name="context_SNMPv1">the context for SNMPv1</a></h3>
<p>
For SNMPv1 the context is built out of the following parameters:
</p>
<ul>
<li>The name of the host to which the PDU is sent</li>
<li>The port number on that host</li>
<li>The community name that is used, by default <em>public</em></li>
<li>The type of socket that is used, by default <em>Standard</em> </li>
</ul>

<p>
The <a href="#socket_type">next section</a> explains the use of the type of socket.
</p>

<p>
This SNMP stack provides three contexts for SNMPv1:
</p>
<ul>
<li>uk.co.westhawk.snmp.stack.SnmpContext</li>
<li>uk.co.westhawk.snmp.stack.SnmpContextPool</li>
<li>uk.co.westhawk.snmp.stack.PassiveSnmpContext</li>
</ul>

<p>
The <code>SnmpContextPool</code> contains a pool of
<code>SnmpContext</code> and will share any context that it can share.
This results in a reduced number of threads and other resources.
</p>

<p>
The <code>PassiveSnmpContextPool</code> contains the SNMPv1
context that is needed by a PDU to send a SNMPv1 request in
environments where thread creation is unwanted, see the 
<a href="../src/uk/co/westhawk/nothread/notes.html" target="_top">nothread</a>
notes. 
</p>

<h3 class="q"><a name="context_SNMPv2c">the context for SNMPv2c</a></h3>
<p>
The context for SNMPv2c is very similar to the SNMPv1 context. 
It is built out of the following parameters:
</p>
<ul>
<li>The name of the host to which the PDU is sent</li>
<li>The port number on that host</li>
<li>The community name that is used, by default <em>public</em></li>
<li>The type of socket that is used, by default <em>Standard</em> </li>
</ul>

<p>
The <a href="#socket_type">next section</a> explains the use of the type of socket.
</p>

<p>
This SNMP stack provides three contexts for SNMPv2c:
</p>
<ul>
<li>uk.co.westhawk.snmp.stack.SnmpContextv2c</li>
<li>uk.co.westhawk.snmp.stack.SnmpContextv2cPool</li>
<li>uk.co.westhawk.snmp.stack.PassiveSnmpContextv2c</li>
</ul>


<p>
The <code>SnmpContextv2cPool</code> contains a pool of
<code>SnmpContextv2c</code> and will share any context that it can share.
This results in a reduced number of threads and other resources.
</p>

<p>
The <code>PassiveSnmpContextv2c</code> contains the SNMPv2c
context that is needed by a PDU to send a SNMPv2c request in
environments where thread creation is unwanted, see the 
<a href="../src/uk/co/westhawk/nothread/notes.html" target="_top">nothread</a>
notes. 
</p>

<h3 class="q"><a name="context_SNMPv3">the context for SNMPv3</a></h3>
<p>
For SNMPv3 the context is built out of the following parameters.
</p>
<ul>
<li>The name of the host to which the PDU is sent</li>
<li>The port number on that host</li>
<li>The type of socket that is used, by default <em>Standard</em> </li>
<li>The user name of the SNMP principle, by default <em>initial</em></li>
<li>Whether the user wants to use authentication or not, by default
<em>false</em></li>
<li>The user authentication password</li>
<li>The authentication protocol the user wants to use, by default <em>MD5</em></li>
<li>Whether the user wants to use privacy or not, by default
<em>false</em></li>
<li>The user privacy password</li>
<li>The context engine id of the host (<em>not</em> to be confused with
the SNMP Engine ID, see 
<a href="#authoritative_engine">authoritative engine</a>)
</li>
<li>The context name of the host, by default the <em>empty</em> string</li>
</ul>


<p>
This SNMP stack provides two contexts for SNMPv3:
</p>
<ul>
<li>uk.co.westhawk.snmp.stack.SnmpContextv3</li>
<li>uk.co.westhawk.snmp.stack.SnmpContextv3Pool</li>
</ul>

<p>
The <code>SnmpContextv3Pool</code> contains a pool of
<code>SnmpContextv3</code> and will share any context that it can share.
This results in a reduced number of threads and other resources.
</p>

<p>
When sending traps or receiving request PDUs with SNMPv3, please read 
the section about the
<a href="#authoritative_engine">authoritative engine</a>.
</p>


<h1><a name="socket_type">The socket type</a></h1>
<p>
At the moment two types of sockets can be used:
</p>
<ul>
<li>The standard (UDP) socket, defined by
<code>SnmpContextBasisFace.STANDARD_SOCKET</code></li>
<li>The TCP socket, defined by
<code>SnmpContextBasisFace.TCP_SOCKET</code></li>
</ul>


<p>
By default the standard socket will be used. 
</p>
<p>
The TCP socket can be used for "Reliable SNMP", if your agent supports
this.
This socket can be used to send requests and listen for traps, however
it doesn't provide the functionality to send a response back to a
request, see <a href="#response">sending a response to a request</a>.
</p>


<h1><a name="usage">Sending PDUs</a></h1>
<p>
Sending PDUs can be done in a number of ways:
</p>
<ul>
<li>Using the <a href="#beans">beans</a></li>
<li>Using the <a href="#pdus">PDUs</a>, i.e. a request, inform, trap or
response PDU</li>
<li>Using the <a href="#blocking_calls">blocking calls</a></li>
</ul>


<h2><a name="beans">Using the beans</a></h2>
<p>
The package <code>uk.co.westhawk.snmp.beans</code> 
contains all the beans in the stack. 
Except for the <code>UsmDiscoveryBean</code> and
<code>UsmBeingDiscoveredBean</code> they all (still) relate to
SNMPv1. 
</p>
<p>
The beans form a bridge between the <code>uk.co.westhawk.snmp.pdu</code> (and
<code>uk.co.westhawk.snmp.stack</code>) package(s) and any applet 
or application you may want to write.
</p>
<p>
The beans work via the (asynchronous)
<code>java.beans.PropertyChange</code> mechanism. 
If you are using Swing, don't forget to use
<code>javax.swing.SwingUtilities.invokeLater(java.lang.Runnable)</code> 
if you want to do any screen updates from the
<code>propertyChange</code> method.
</p>
<p>
Our beans gather specific MIB information, i.e. the OID (Object
Identifier) is hard coded. The beans should be easy enough to
understand, and with little effort you can write a bean for your own purpose.
The beans <code>SNMPBean</code> and <code>SNMPRunBean</code>
contain some general information about the beans.
The coding <a href="#example">examples</a> will show you how to use the
beans as well.
</p>

<h2><a name="pdus">Using the PDUs</a></h2>
<p>
The package
<code>uk.co.westhawk.snmp.pdu</code> contains all the public accessible
PDUs.
All the PDUs (well, except for the <a href="#blocking_calls">BlockPdu</a>) 
extend abstract
<code>uk.co.westhawk.snmp.stack.Pdu</code>. 
The PDUs are non blocking and work via the
<code>java.util.Observer/java.util.Observable</code> mechanism. 
</p>
<p>
The idea is that for each class of problem you should subclass the
abstract <code>uk.co.westhawk.snmp.stack.Pdu</code> class. You will have
to implement the <code>protected void new_value(int n, varbind
res)</code> and the <code>protected void tell_them()</code> methods.
As example look at the <code>uk.co.westhawk.snmp.pdu.OneIntPdu</code>
class or any other class in that package.
</p>

<p>
In order to use a PDU do the following:
</p>
<ol>
<li>Create a <a href="#context">context</a>, giving it the host name and 
port number of your SNMP agent. If this is run in an applet then you can
only connect back to that server (unless you sign the applet)! </li>
<li>Create a PDU, passing it the context; <code>GetPdu pdu = new
GetPdu(context)</code>. </li>
<li>Add the OIDs you are interested in with 
<code>pdu.add_oid(oid)</code>.  </li>
<li>Add an observer with <code>pdu.addObserver(observer)</code>. The argument is the
object that wishes to be notified when the new value arrives. 
It must implement
<code>java.util.Observer</code>, that is it must have a
<code>public void update(java.util.Observable obs, java.lang.Object obj)</code>
method. This method will get called when the value arrives. 
If you are using Swing, don't forget to use
<code>javax.swing.SwingUtilities.invokeLater(java.lang.Runnable)</code> 
if you want to do any screen updates.</li>
<li>Call <code>pdu.send()</code>.</li>
<li>Sleep, or do something else. Your <code>update</code> method will get 
called automatically when the data has arrived. Both the context and PDU
objects spawn their own threads, so there is nothing further to do.</li>
</ol>


<p>
The stack was initially build with manager only functionality in mind,
i.e. sending a request and receiving a response. 
It is possible to receive a request and 
<a href="#response">send a response back</a>, but 
the functionality is still very clunky.
</p>

<p>
Since a trap or a response does not get a reply, you can omit adding an
<code>observer</code> (step 4)
and implementing <code>update</code> (the last step) when sending one.
When sending traps or receiving PDUs with SNMPv3, please read the
section about the
<a href="#authoritative_engine">authoritative engine</a>.
</p>

<p>
The coding <a href="#example">examples</a> will show you how to use the
PDUs as well.
</p>

<h2><a name="blocking_calls">Using the blocking calls</a></h2>
<p>
The class <code>uk.co.westhawk.snmp.pdu.BlockPdu</code> is a wrapper
class around the traditional (non blocking) PDU. It allows the user to
send either a Set request, a Get request, a GetNext request or a GetBulk
request by
specifying the type of request, see the <code>setPduType</code> method. The 
caller has to add the necessary OIDs with the method <code>addOid</code>.
</p>
<p>
As the title suggests, the BlockPdu sends the request and waits for the
response. 
We suggest that you only use this class if you have to;
because the PDU blocks, you can not do anything else on
that thread while it is waiting for a reply. If that thread is driving a
UI, then the user may see a sluggish interface. 
If you can, use the <a href="#beans">beans</a> or the <a
href="#pdus">PDUs</a>. They are much faster as well.
</p>

<p>
There are four methods that send the request, wait for the response and
return the variables or variable bindings. They throw the
<code>uk.co.westhawk.snmp.stack.PduException</code> exception:
</p>
<ul>
<li>AsnObject getResponseVariable()</li>
<li>AsnObject [ ] getResponseVariables()</li>
<li>varbind getResponseVariableBinding()</li>
<li>varbind [ ] getResponseVariableBindings()</li>
</ul>


<p>
The OIDs that are added via <code>addOid</code> method for the request
will not be replaced by the OIDs from the response. This means that
every request will result in the same answer and that the GetNext does
not <em>walk</em> the MIB
</p>
<h1><a name="receiving_pdus">Receiving PDUs</a></h1>
<p>
There are different ways to receive incoming PDUs.
Any combination of these ways can be used at the same time:
</p>
<ul>
<li>Receive <a href="#specific_host_trap">trap PDUs from a specific host</a></li>
<li>Receive <a href="#specific_host_request">request PDUs from a specific host</a></li>
<li>Receive <a href="#all_pdus">PDUs from all hosts</a></li>
<li>Receive <a href="#unhandled_pdus">unhandled PDUs</a></li>
</ul>
The conventional and default port to listen for request PDUs is
<em>161</em>, for traps this is <em>162</em>.
Since on UNIX and Linux systems only the <code>root</code> user is allowed 
to open these port, you will have to run as <code>root</code> in order to 
listen for incoming PDUs on that port, when running on any of those
operating systems.


<h3 class="q"><a name="specific_host_trap">Receiving trap PDUs from a specific host</a></h3>
<p>
To receive traps, that is a <code>Trapv1</code> or <code>Trapv2</code> 
PDU, from a specific host do the following:
</p>
<ul>
<li>Create or reuse a <a href="#context">context</a> with the host name and 
parameters of your SNMP agent. The port number of the context will be
ignored, but is set in the next step.</li>
<li>Add a trap listener with
<code>context.addTrapListener(listener, port)</code>. 
The arguments are the object that wishes to be notified when the traps 
arrive and the listening port. 
It must implement
<code>uk.co.westhawk.snmp.event.TrapListener</code>, that is it must have a
<code>public void trapReceived(uk.co.westhawk.snmp.event.TrapEvent evt)</code>
method. This method will get called when the trap is received.</li>
</ul>
<p>
The <code>SnmpContext</code> fires 
<a href="#decoded_pdu_event">decoded</a>
PDU events.
</p>

<h3 class="q"><a name="specific_host_request">Receiving request PDUs from a specific host</a></h3>
<p>
To receive request PDUs, that is a <code>GetRequest</code>, 
<code>SetRequest</code>, <code>GetNextRequest</code>, 
<code>GetBulkRequest</code> or <code>Inform</code> PDU, 
from a specific host do the following:
</p>
<ul>
<li>Create or reuse a <a href="#context">context</a> with the host name and 
parameters of your SNMP agent. The port number of the context will be
ignored, but is set in the next step.</li>
<li>Add a request PDU listener with
<code>context.addRequestPduListener(listener, port)</code>. 
The arguments are the object that wishes to be notified when the 
request PDUs arrive and the listening port. It must implement
<code>uk.co.westhawk.snmp.event.RequestPduListener</code>, that is it must 
have a
<code>public void requestPduReceived(uk.co.westhawk.snmp.event.RequestPduEvent evt)</code>
method. This method will get called when the request PDU is received.</li>
</ul>
<p>
The <code>SnmpContext</code> fires 
<a href="#decoded_pdu_event">decoded</a>
PDU events. If you want to reply to the request, read the section on
<a href="#response">sending a response</a>.
</p>


<p>
When receiving request PDUs with SNMPv3, please read the section about the
<a href="#authoritative_engine">authoritative engine</a>.
</p>



<h3 class="q"><a name="all_pdus">Receiving PDUs from all hosts</a></h3>
<p>
The class <code>uk.co.westhawk.snmp.stack.ListeningContextPool</code>
forms the base to receiving incoming packets. It contains a pool of
<code>uk.co.westhawk.snmp.stack.ListeningContext</code> objects, that
prevent the user from opening more than one listening object on the same
port.
</p>
<ul>
<li>Get an instance of the pool with <code>ListeningContextPool lContext
= new ListeningContextPool(port)</code>.
The argument is the listening port.
</li>
<li>Add a raw PDU listener with
<code>lContext.addRawPduListener(listener)</code>. 
The argument is the object that wishes to be notified when the raw PDUs arrive. 
It must implement
<code>uk.co.westhawk.snmp.event.RawPduListener</code>, that is it must have a
<code>public void rawPduReceived(uk.co.westhawk.snmp.event.RawPduEvent evt)</code>
method. This method will get called when the packet is received.</li>
</ul>
<p>
The <code>ListeningContext</code> fires 
<a href="#undecoded_pdu_event">undecoded</a>
PDU events.
</p>

<h3 class="q"><a name="unhandled_pdus">Receiving unhandled PDUs</a></h3>
<p>
Unhandled PDUs are raw PDUs that are received (see 
<a href="#all_pdus">PDUs for all hosts</a>)
but do not match any of the contexts (see
<a href="#specific_host_trap">trap PDUs from a specific host</a> and
<a href="#specific_host_request">request PDUs from a specific host</a>):
</p>
<ul>
<li>Get an instance of the pool with <code>ListeningContextPool lContext
= new ListeningContextPool(port)</code>.
The argument is the listening port.
</li>
<li>Add an unhandled raw PDU listener with
<code>lContext.addUnhandledRawPduListener(listener)</code>. 
The argument is the
object that wishes to be notified when unhandled PDUs are received. 
It must implement
<code>uk.co.westhawk.snmp.event.RawPduListener</code>, that is it must have a
<code>public void rawPduReceived(uk.co.westhawk.snmp.event.RawPduEvent evt)</code>
method. This method will get called when the packet is received and
remains unhandled.</li>
</ul>
<p>
The <code>ListeningContext</code> fires 
<a href="#undecoded_pdu_event">undecoded</a>
PDU events.
</p>

<h1><a name="pdu_events">The PDU events</a></h1>
<p>
There are two types of PDU events:
</p>
<ul>
<li>The <a href="#decoded_pdu_event">decoded PDU events</a> where a 
decoded request PDU or trap PDU is passed</li>
<li>The <a href="#undecoded_pdu_event">undecoded PDU events</a> where
the raw bytes of an incoming message are passed</li>
</ul>
All events are fired in a separate thread, so the listening
context can go straight back to listening.


<h3 class="q"><a name="decoded_pdu_event">The decoded PDU events</a></h3>
<p>
Decoded PDU events are fired by the <code>SnmpContext</code> classes
when receiving <a href="#specific_host_trap">trap PDUs from a specific host</a> 
or <a href="#specific_host_request">request PDUs from a specific host</a>.
</p>
<p>
When receiving 
<a href="#specific_host_trap">trap PDUs from a specific host</a> 
the <code>uk.co.westhawk.snmp.event.TrapEvent</code> 
will contain one of the two trap PDUs:
</p>
<ul>
<li><code>uk.co.westhawk.snmp.stack.TrapPduv1</code> - The Trap PDU for
SNMPv1</li>
<li><code>uk.co.westhawk.snmp.stack.TrapPduv2</code> - The Trap PDU for
SNMPv2c and SNMPv3</li>
</ul>


<p>
When receiving 
<a href="#specific_host_request">request PDUs from a specific host</a>  
the <code>uk.co.westhawk.snmp.event.RequestPduEvent</code> 
will contain one of the following request PDUs:
</p>
<ul>
<li><code>uk.co.westhawk.snmp.stack.GetPdu</code> - The GetRequest PDU</li>
<li><code>uk.co.westhawk.snmp.stack.SetPdu</code> - The SetRequest PDU</li>
<li><code>uk.co.westhawk.snmp.stack.GetNextPdu</code> - The GetNextRequest PDU</li>
<li><code>uk.co.westhawk.snmp.stack.GetBulkPdu</code> - The GetBulkRequest PDU (SNMPv2c and SNMPv3 only)</li>
<li><code>uk.co.westhawk.snmp.stack.InformPdu</code> - The Inform PDU (SNMPv2c and SNMPv3 only)</li>
</ul>

<p>
In both cases the event will contain the following:
</p>
<ul>
<li><code>snmp context</code> - The snmp context that decoded the PDU</li>
<li><code>pdu</code> - The PDU</li>
<li><code>port</code> - The port number of the host where the
PDU came from</li>
</ul>

<h3 class="q"><a name="undecoded_pdu_event">The undecoded PDU events</a></h3>
<p>
Undecoded PDU events are fired by the <code>ListeningContext</code> class
when receiving <a href="#all_pdus">PDUs for all hosts</a> and/or
receiving <a href="#unhandled_pdus">unhandled PDUs</a>.
The <code>uk.co.westhawk.snmp.event.RawPduEvent</code> 
will contain the following:
</p>
<ul>
<li><code>listening context</code> - The listening context that received the PDU</li>
<li><code>version</code> - The SNMP version number of the PDU</li>
<li><code>host address</code> - The IP host address of the host where the
PDU came from</li>
<li><code>port</code> - The port number of the host where the
PDU came from</li>
<li><code>message</code> - The PDU in bytes</li>
</ul>


<p>
To decode an undecoded PDU event, you create a 
<a href="#context">context</a> on the fly and call 
<code>Pdu pdu = context.processIncomingPdu(byte[ ] message)</code>.
The context should contain all the parameters needed to decode the
message. For SNMPv3 this is not so obvious.
</p>


<h1><a name="response">Sending a response to a request</a></h1>
<p>
The stack was initially build with manager only functionality in mind,
i.e. sending a request and receiving a response. 
It is possible to 
<a href="#specific_host_request">receive a request</a> by getting
<a href="#decoded_pdu_event">decoded PDU events</a>
and send a response back, but 
the functionality is still very clunky.
</p>
<p>
The TCP_SOCKET does not provide the functionality to send a response
back. You'll have to use the standard one, see the section on
<a href="#socket_type">socket type</a>.
</p>
<p>
As mentioned before, the stack offers no MIB parsing to help the user
parse the request PDU. It is possible to send a
<code>uk.co.westhawk.snmp.stack.ResponsePdu</code>, 
but how to fill it in is up to the user. Please do not forget to use the
<code>RequestPduEvent.getHostPort()</code> when creating the context for
the response.
</p>
<p>
When sending response PDUs with SNMPv3, please read the next section about 
the <a href="#authoritative_engine">authoritative engine</a>.
</p>


<h1><a name="authoritative_engine">The authoritative engine</a></h1>
<p>
When sending traps or receiving requests the stack becomes
an agent, or an <em>authoritative</em> engine as it is called in SNMPv3, rather
than a manager, or a <em>non-authoritative</em> engine as it is called in
SNMPv3.
</p>
<p>
In SNMPv3 the User-Based Security Model (USM) timeliness mechanism 
is different for authoritative and non-authoritative SNMP engines:
</p>
<ul>
<li>a non-authoritative engine must remain loosely
synchronised with an authoritative engine</li>
<li>an authoritative engine must maintain it snmpEngineBoots and
snmpEngineTime</li>
</ul>
<p>
This distinction does not apply to SNMPv1 or SNMPv2c.
</p>

<p>
Since the stack is not a <em>real</em> agent, it cannot provide all the
USM synchronisation parameters. For that reason the user has to provide
an implementation of the interface 
<code>uk.co.westhawk.snmp.stack.UsmAgent</code>. See also the javadoc on
<code>SnmpContextv3</code>. This interface provides
the stack with the following information of its authoritative engine:
</p>
<ul>
<li><code>Engine ID</code> - The authoritative SNMP Engine ID, which (at
least within an administrative domain) uniquely and unambiguously
identifies the SNMP engine (<em>not</em> to be confused with the context
engine id, see <a href="#context_SNMPv3">SNMPv3 context</a>)
</li>
<li><code>Engine Boots</code> - The authoritative SNMP Engine Boots,
which is a count of the number of times the SNMP engine has
re-booted/re-initialized since snmpEngineID was last configured</li> 
<li><code>Engine Time</code> - The authoritative SNMP Engine Time, which is the number of seconds since the snmpEngineBoots counter was last incremented</li>
</ul>


<h1><a name="example">Coding example</a></h1>
<p>
The stack contains a lot of examples in the form of 
applications in the package <code>uk.co.westhawk.examplev1</code>. 
The package <code>uk.co.westhawk.examplev2c</code> contains a few examples
for SNMPv2c.
The package <code>uk.co.westhawk.examplev3</code> contains a few examples
for SNMPv3.
These packages show you how to use the PDUs and beans. Note that because
we implemented SNMPv3 before SNMPv2c, there are more examples for the
former one.
</p>
<p>
How to run these examples is explained in the 
<a href="#runExample">next</a> section. 
If this example is not sufficient, check if the other examples do what you
are looking for.
</p>

<p>
The next is a snippet of the  
<code>uk.co.westhawk.examplev1.get_next</code> example that walks 
the MIB with the GetNextPdu. 
The complete example is part of the source distribution.
</p>
<pre>
public class get_next implements Observer
{

    public void init() 
    {
        try 
        {
            context = createContext(host, port, socketType, community);
            GetNextPdu pdu = createPdu(context, new varbind(oid), this);
            pdu.send();
        }
        catch (java.io.IOException exc)
        {
            context.destroy();
            System.exit(1);
        }
        catch(uk.co.westhawk.snmp.stack.PduException exc)
        {
            context.destroy();
            System.exit(1);
        }
    }

    protected SnmpContext createContext(String host, int port, String socketType, 
    String community)
    throws java.io.IOException
    {
        SnmpContext con = new SnmpContext(host, port, socketType);
        con.setCommunity(community);
        return con;
    }

    protected GetNextPdu createPdu(SnmpContext context, varbind var, Observer obs)
    {
        GetNextPdu newPdu = new GetNextPdu(context);
        newPdu.addOid(var);
        newPdu.addObserver(obs);
        return newPdu;
    }

    public void update(Observable obs, Object ov)
    {
        GetNextPdu pdu = (GetNextPdu) obs;
        if (pdu.getErrorStatus() == AsnObject.SNMP_ERR_NOERROR)
        {
            try
            {
                varbind[] vars = pdu.getResponseVarbinds();
                varbind var = vars[0];
                System.out.println(var.toString());

                pdu = createPdu(context, new varbind(var.getOid()), this);
                pdu.send();
            }
            catch(java.io.IOException exc)
            {
                System.out.println("update(): IOException " 
                      + exc.getMessage());
            }
            catch(uk.co.westhawk.snmp.stack.PduException exc)
            {
                System.out.println("update(): PduException " 
                      + exc.getMessage());
            }
        }
        else
        {
            context.destroy();
            System.exit(0);
        }
    }
}
</pre>



<h1><a name="run">Running the applications</a></h1>

<h3 class="q"><a name="runExample">Running the stack examples</a></h3>
<p>
To run the examples, you need to have Ant installed.
</p>
<p>
The <code> uk.co.westhawk.examplev1</code>, 
<code> uk.co.westhawk.examplev2c</code> and 
<code> uk.co.westhawk.examplev3</code> 
directories contain example applications, that can be run
using the Ant <code>runExample</code> target, defined in
<code>example.xml</code>. 
</p>
<p>
Type on the command line:
</p>
<pre>
% ant runExample
</pre>

<p>
Unless changed (see below), this target will run the <code>
uk.co.westhawk.examplev1.get_next</code> application, 
with the properties file
<code>src/uk/co/westhawk/examplev1/get_next.properties</code> as argument.
</p>


<p>
The <code>runExample</code> target has a number of properties (defined
in <code>example.xml</code>) that you 
can change to run another example:
</p>
<ul>
  <li>
    <code>package.name</code>; the Java package name, default set to 
    <code>uk.co.westhawk.examplev1</code>
  </li>
  <li>
    <code>package.dir</code>; the directory on disk where the package lives
    (relative to <code>example.xml</code>), default set 
    to <code>src/uk/co/westhawk/examplev1</code>
  </li>
  <li>
    <code>classname</code>; the application name (without the package name), 
    default set to <code>get_next</code>
  </li>
  <li>
    <code>propertiesfile</code>; the properties file that is
    passed as (optional) argument, default set to
    <code>src/uk/co/westhawk/examplev1/get_next.properties</code>
  </li>
</ul>

<p>
The properties file (<code>get_next.properties</code>)
contains the initialisation parameters of the example, such as the hostname 
and the port number.
When the argument is missing, the application will look for the 
file <code>&lt;classname&gt;.properties</code> in the used package directory.
</p>

<p>
The target first compiles the package (into the directory
<code>classes</code>) and then runs it. The classpath is set to:
</p>
<ul>
  <li>
    <code>snmp&lt;version&gt;.jar</code>; 
    to change the location, alter the property <code>snmp.jar</code> at
    the top of the <code>build.xml</code> file.
  </li>
  <li>
    <code>tablelayout.jar</code>;
    to change the location, alter the property <code>table.jar</code> at
    the top of the <code>build.xml</code> file.
  </li>
</ul>


<h3 class="q"><a name="runStubBrowser">Running the Stub Browser</a></h3>
<p>
The Stub Browser is an experimental piece of software that offers the
user a UI to generate a PDU out of selected OIDs. It is an add-on to
the Mibble 
<a href="http://www.mibble.org/doc/faq/applications/index.html#Q2"
target="outside">
Mib Browser</a>. 
It is not "fool-proof", and (as always) we appreciate your feedback.
</p>

<p>
To run the Stub Browser you need to have Ant installed. 
You have to download
</p>
<ul>
  <li>
      the <code>stubBrowser&lt;version&gt;.zip</code> from the 
      <a href="http://snmp.westhawk.co.uk/index.html" target="outside">
      Westhawk's SNMP</a> page 
  </li>
  <li>
      the Java MIB browser 
      <a href="http://www.mibble.org" target="outside">Mibble</a> (v2.5 or later).
  </li>
</ul>
<p>
and configure the location of
</p>
<ul>
  <li>
      the Mibble distribution, by changing the 
      property <code>mibble.dir</code> in the <code>build.xml</code> file.
  </li>
  <li>
      the <code>snmp&lt;version&gt;.jar</code> file, by changing 
      the property <code>snmp.jar</code> in the <code>build.xml</code> 
      file, unless you installed both zip files in the same directory.
  </li>
</ul>

<p>
Now run on the command line:
</p>
<pre>
% ant runStubBrowser
</pre>

<p>
First select all the OIDs you want to include in your Java stub file. 
Select an OID be by right clicking on a leaf in the MIB tree. 
A small popup menu will appear with the "Add to Stubs" menu item. 
Each selected stub will be listed in the lower pane.
</p>
<p>
When you are happy with your list, select "Generate Stubs" from the File
menu. This will bring up a second "Stub Files" frame with the Java code.
Every time you generate a stub file, the new code will be added in a new
tab. 
</p>
<p>
You can save each tab individually to disk. The code will try to replace the
classname and packagename place holders, but please check the code
before trying to compile. Compilation of the new java files, is outside
the scope of the Stub Browser.
</p>
<p>
Please note that the Stub Browser is not a fancy development tool. For
example, when exiting the application or closing a tab, it will not
check if you have saved the latest version.
</p>


<h1><a name="reading">Reading</a></h1>
<p>
Our article on Simple Times (issue Dec 2001) explains the 
<a href="http://www.simple-times.org/pub/simple-times/issues/9-1.html#tools"
target="outside">
history and design decisions</a> 
of the stack.
</p>

<p>
The <a href="http://www.simpleweb.org/" target="outside">SimpleWeb</a> 
provides links and information on network management, including software, RFCs and tutorials. 
The focus is on SNMP and Internet management.
</p>

<p>
For more background on SNMP we recommend the following books:
</p>
<ul>
<li>The Simple Book by Marshall T. Rose (Prentice Hall, 1996),
ISBN 0-134-51659-1
</li>
<li>SNMP, SNMPv2, SNMPv3 and RMON 1 and 2 
by William Stallings (Addison-Wesley, 1999), 
ISBN 0-201-48534-6
</li>
</ul>



<h1><a name="third_party">Third party packages</a></h1>
<p>
All the jar files that are needed for the <em>core</em> stack are
delivered with the stack. A few jar files are used in other packages
(mostly the examples) that do not come with the stack: 
</p>
<ul>
<li>
    <a href="http://ant.apache.org" target="outside">Ant</a> (v1.5.4) from 
    Apache is used to run the examples and (re)build the stack.
</li>
<li>
    <a href="http://www.mibble.org" target="outside">Mibble</a> (v2.5) is a 
    Java MIB browser that is needed to run the Stub Browser application.
</li>
<li>
    <a href="http://xml.apache.org/xerces2-j" target="outside">XML parser</a> 
    (v2.6.2) for Java from IBM is used for the treeviewer target.
</li>
<li>
    <a href="http://java.sun.com/products/servlet/download.html" 
    target="outside">Java Servlets</a> (v1.2.2) from Sun Microsystems
    for the servlets examples.
</li>
<li>
    <a href="http://prefuse.org/download/" target="outside">Prefuse</a>
    Beta for the examplev2c.MonitorAsteriskGraph example.
</li>
</ul>

<p>
Some of the examples use the 
<a href="http://www.westhawk.co.uk/technology/snmp/index.shtml" target="outside">TableLayout</a>
layout manager. This layout manager is part of the distribution. For
those who retrieved the stack from SourceForge, the layout manager can
be downloaded from our 
<a href="http://www.westhawk.co.uk/technology/snmp/index.shtml" target="outside">SNMP Technology</a>
page as a zip file. Unzip the <code>tablelayout.jar</code> file into
the <code>lib/</code> directory.
</p>

<p>
The stack uses version 1.27 of the 
<a href="http://www.bouncycastle.org/">Bouncy Castle</a> 
lightweight cryptography (lcrypto) API for SNMPv3 authentication and
privacy. The files of this great API that are used by the stack, are
distributed as part of the stack, so don't have to be downloaded
separately. They are part of the SourceForge cvs as well.
</p>


<h1><a name="copyright">Copyright &amp; License</a></h1>
<p>
The stack is freeware.
The licence (see the header of each file) means that you can do whatever
you like with it without cost, except
</p>
<ol>
<li>blame us when it does/doesn't work</li>
<li>remove our copyright</li>
</ol>


<p>
The licence requires that you acknowledge our code, by mentioning its
origin in the documentation of any product that uses it (in some cases
there may be no documentation).
</p>

<p>
The Stub Browser is released under the GNU GPL License, 
since it uses Mibble.
There are no commercial licence fees, nor do we have any GPL-style
open-source requirements on our stack itself.
</p>

<p>
If you would like software written that uses the stack or modifications
to the stack to better suit your project, we would be happy to quote you
for the work.
</p>

<p>
We also offer commercial support for organisations who want it.
</p>

<hr/>

<p>
<small>
17 Oct 2007
</small>
</p>

<a name="contact"/> 
<p>
<small>
Post to the 
<a
href="https://lists.sourceforge.net/lists/listinfo/westhawksnmp-snmp"
target="outside">snmp mailing list</a>
or contact the
<a href="mailto:snmp@westhawk.co.uk">snmp group</a>
at
<a href="http://www.westhawk.co.uk" target="outside">Westhawk Ltd</a>
</small>
</p>


</body>
</html>
